---
title: 구성 참조
i18nReady: true
githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/%40types/astro.ts
---

import Since from '~/components/Since.astro';
import DontEditWarning from '~/components/DontEditWarning.astro';

다음 참조는 Astro에서 지원되는 모든 구성 옵션을 다룹니다. Astro 구성에 대해 자세히 알아보려면 [Astro 구성](/ko/guides/configuring-astro/) 안내서를 읽어보세요.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 구성 옵션은 여기에 작성합니다...
});
```

## 최상위 옵션

### site

<p>

**타입:** `string`

</p>

배포된 최종 URL입니다. Astro는 이 전체 URL을 사용하여 최종 빌드에서 사이트맵과 표준 URL을 생성합니다. Astro를 최대한 활용하려면 이 구성을 설정하는 것이 좋습니다.

```js
{
  site: 'https://www.my-site.dev';
}
```

### base

<p>

**타입:** `string`

</p>

배포할 기본 경로입니다. Astro는 개발 및 프로덕션 빌드 모두에서 이 경로를 페이지 및 자산의 루트로 사용합니다.

아래 예에서 `astro dev`는 `/docs`에서 서버를 시작합니다.

```js
{
  base: '/docs';
}
```

이 옵션을 사용할 때 모든 정적 자산 가져오기 및 URL은 base를 접두사로 추가해야 합니다. `import.meta.env.BASE_URL`을 통해 이 값에 액세스할 수 있습니다.

`import.meta.env.BASE_URL`의 값은 `base`에 어떤 값을 설정했는지에 관계없이 `trailingSlash` 구성에 의해 결정됩니다.

`trailingSlash: "always"`가 설정된 경우 후행 슬래시가 항상 포함됩니다. `trailingSlash: "never"`가 설정된 경우 `base`에 슬래시가 포함되어 있더라도 `BASE_URL`에는 후행 슬래시가 포함되지 않습니다.

또한 Astro는 통합에 사용할 수 있도록 하기 전에 `config.base`의 구성된 값을 내부적으로 조작합니다. 통합에서 읽은 `config.base` 값도 동일한 방식으로 `trailingSlash` 구성에 따라 결정됩니다.

아래 예시에서, `import.meta.env.BASE_URL` 및 `config.base` 값은 모두 `/docs`가 됩니다.

```js
{
	 base: '/docs/',
	 trailingSlash: "never"
}
```

아래 예시에서 `import.meta.env.BASE_URL` 및 `config.base` 값은 모두 `/docs/`가 됩니다.

```js
{
	 base: '/docs',
	 trailingSlash: "always"
}
```

### trailingSlash

<p>

**타입:** `'always' | 'never' | 'ignore'`<br />
**기본값:** `'ignore'`

</p>

개발 서버의 경로 일치 동작을 설정합니다. 다음 옵션 중에서 선택하세요.

- `'always'` - 후행 슬래시가 포함된 URL만 일치시킵니다. (예: "/foo/")
- `'never'` - 후행 슬래시가 포함된 URL은 절대 일치시키지 않습니다. (예: "/foo")
- `'ignore'` - 후행 "/" 존재 여부에 관계없이 URL을 일치시킵니다.

프로덕션 호스트에서 후행 슬래시 작동 여부를 엄격하게 처리하는 경우 이 구성 옵션을 사용하세요.

또한 개발 중에 슬래시가 있거나 없는 URL이 작동하지 않도록 더 엄격하게 설정하려는 경우 이를 설정할 수도 있습니다.

```js
{
  // 예: 개발 중에 후행 슬래시가 필요합니다.
  trailingSlash: 'always';
}
```

**참고하기:**

- build.format

### redirects

<p>

**타입:** `Record.<string, RedirectConfig>`<br />
**기본값:** `{}`<br />

<Since v="2.9.0" />
</p>

키는 일치시킬 경로이고 값은 리디렉션할 경로인 리디렉션 매핑을 지정합니다.

정적 경로와 동적 경로를 모두 리디렉션할 수 있지만 동일한 종류의 경로로만 리디렉션할 수 있습니다.
예를 들어 `'/article': '/blog/[...slug]'` 리디렉션을 사용할 수 없습니다.

```js
{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}
```

어댑터가 설치되지 않은 정적으로 생성된 사이트의 경우 [`<meta http-equiv="refresh">` 태그](https://developer.mozilla.org/ko/docs/Web/HTML/Element/meta#http-equiv)를 사용하여 클라이언트 리디렉션을 생성하며 상태 코드는 지원하지 않습니다.

`output: static` 모드에서 SSR을 사용하거나 정적 어댑터를 사용하는 경우 상태 코드가 지원됩니다.
Astro는 `301` 상태로 리디렉션된 GET 요청을 처리하고 다른 요청 방법에는 `308` 상태를 사용합니다.

리디렉션 구성의 객체를 사용하여 [리디렉션 상태 코드](https://developer.mozilla.org/ko/docs/Web/HTTP/Status#%EB%A6%AC%EB%8B%A4%EC%9D%B4%EB%A0%89%EC%85%98_%EB%A9%94%EC%8B%9C%EC%A7%80)를 맞춤설정할 수 있습니다.

```js
{
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
}
```

### output

<p>

**타입:** `'static' | 'server' | 'hybrid'`<br />
**기본값:** `'static'`

</p>

빌드의 출력 대상을 지정합니다.

- `'static'` - 모든 정적 호스트에 배포될 정적 사이트를 구축합니다.
- `'server'` - SSR (서버 측 렌더링)을 지원하는 호스트에 배포할 앱을 구축합니다.
- `'hybrid'` - 몇 개의 서버 측 렌더링 페이지가 포함된 정적 사이트를 구축합니다.

```js
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
});
```

**참고하기:**

- adapter

### adapter

<p>

**타입:** `AstroIntegration`

</p>

빌드 어댑터를 사용하여 선호하는 서버, 서버리스, 에지 호스트에 배포하세요. Astro SSR을 사용하려면 [Netlify](/ko/guides/deploy/netlify/#ssr용-어댑터), [Vercel](/ko/guides/deploy/vercel/#ssr용-어댑터) 등을 위한 자사 어댑터 중 하나를 가져오세요.

SSR에 대한 자세한 내용은 [서버 측 렌더링 안내서를 참조](/ko/guides/server-side-rendering/)하고, 전체 호스트 목록은 [배포 안내서](/ko/guides/deploy/)를 참조하세요.

```js
import netlify from '@astrojs/netlify';
{
  // 예: Netlify 서버리스 배포를 위한 빌드
  adapter: netlify(),
}
```

**참고하기:**

- output

## integrations

맞춤형 통합으로 Astro를 확장하세요. 통합은 프레임워크 지원 (Solid.js 등), 새로운 기능 (사이트맵 등), 새 라이브러리(Partytown 등)를 한번에 추가하는 것을 도와줍니다.

Astro 통합을 시작하는 데 도움이 필요하면 [통합 안내서](/ko/guides/integrations-guide/)를 읽어보세요.

```js
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // 예: Astro에 React + Tailwind 지원 추가
  integrations: [react(), tailwind()];
}
```

### root

<p>

**타입:** `string`<br />
**CLI:** `--root`<br />
**기본값:** `"."` (현재 작업 디렉터리)

</p>

프로젝트 루트 디렉터리가 아닌 디렉터리에서 `astro` CLI 명령을 실행하는 경우에만 이 옵션을 제공해야 합니다. 일반적으로 이 옵션은 [Astro 구성 파일](/ko/guides/configuring-astro/#지원하는-구성-파일-타입) 대신 CLI를 통해 제공됩니다. Astro가 구성 파일을 찾으려면 먼저 프로젝트 루트를 알아야 하기 때문입니다.

상대 경로를 제공하는 경우 (예: `--root: './my-project'`) Astro는 현재 작업 디렉터리를 기준으로 경로를 확인합니다.

#### 예

```js
{
  root: './my-project-directory';
}
```

```bash
$ astro build --root ./my-project-directory
```

### srcDir

<p>

**타입:** `string`<br />
**기본값:** `"./src"`

</p>

Astro가 여러분의 사이트를 읽을 디렉터리를 설정하세요.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  srcDir: './www';
}
```

### publicDir

<p>

**타입:** `string`<br />
**기본값:** `"./public"`

</p>

정적 자산의 디렉터리를 설정합니다. 이 디렉터리의 파일은 개발 중에 `/`에 제공되고 빌드 중에 build 디렉터리에 복사됩니다. 이러한 파일은 변환이나 번들링 없이 항상 있는 그대로 제공되거나 복사됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  publicDir: './my-custom-publicDir-directory';
}
```

### outDir

<p>

**타입:** `string`<br />
**기본값:** `"./dist"`

</p>

`astro build`가 최종 빌드를 작성하는 디렉터리를 설정합니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  outDir: './my-custom-build-directory';
}
```

**참고하기:**

- build.server

### cacheDir

<p>

**타입:** `string`<br />
**기본값:** `"./node_modules/.astro"`

</p>

빌드 아티팩트를 캐싱하기 위한 디렉터리를 설정합니다. 이 디렉터리의 파일은 빌드 시간을 단축하기 위해 후속 빌드에서 사용됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

```js
{
  cacheDir: './my-custom-cache-directory';
}
```

### compressHTML

<p>

**타입:** `boolean`<br />
**기본값:** `true`

</p>

이는 HTML 출력을 최소화하고 HTML 파일의 크기를 줄이는 옵션입니다. 기본적으로 Astro는 `.astro` 컴포넌트에서 줄 바꿈을 포함하여 HTML의 모든 공백을 제거합니다. 이는 개발 모드와 최종 빌드 모두에서 발생합니다.
HTML 압축을 비활성화하려면 `compressHTML` 플래그를 `false`로 설정하세요.

```js
{
  compressHTML: false;
}
```

### scopedStyleStrategy

<p>

**타입:** `'where' | 'class' | 'attribute'`<br />
**기본값:** `'attribute'`<br />

<Since v="2.4" />
</p>

Astro 컴포넌트에서 스타일 범위 지정에 사용되는 전략을 지정합니다. 다음 중에서 선택하세요:

- `'where'` - `:where` 선택자를 사용하면 구체성이 증가하지 않습니다.
- `'class'` - 클래스 기반 선택기를 사용하면 구체성이 +1 증가합니다.
- `'attribute'` - `data-` 속성을 사용하면 구체성이 +1 증가합니다.

Astro 컴포넌트의 요소 선택기가 전역 스타일 기본값 (예: 전역 스타일시트)을 재정의하도록 하려는 경우 `'class'`를 사용하는 것이 도움이 됩니다.
``where'`를 사용하면 구체성을 더 잘 제어할 수 있지만, 적용되는 선택기를 제어하려면 더 높은 구체성 선택기, 레이어 및 기타 도구를 사용해야 합니다.
`'attribute'`를 사용하는 것은 요소의 `class` 속성을 조작하고 자신의 스타일 지정 로직과 Astro의 스타일 적용 사이의 충돌을 피해야 할 때 유용합니다.

### vite

<p>

**타입:** `ViteUserConfig`

</p>

추가 구성 옵션을 Vite에 전달합니다. Astro가 필요할 수 있는 일부 고급 구성을 지원하지 않을 때 유용합니다.

[vitejs.dev](https://ko.vitejs.dev/config/)에서 전체 `vite` 구성 객체 문서를 확인하세요.

#### 예

```js
{
  vite: {
    ssr: {
      // 예: 필요한 경우, 손상된 패키지가 SSR 처리를 건너뛰도록 강제합니다.
      external: ['broken-npm-package'],
    }
  }
}
```

```js
{
  vite: {
    // 예: Astro 프로젝트에 직접 맞춤형 vite 플러그인 추가
    plugins: [myPlugin()],
  }
}
```

## 빌드 옵션

### build.format

<p>

**타입:** `('file' | 'directory' | 'preserve')`<br />
**기본값:** `'directory'`

</p>

각 페이지의 출력 파일 형식을 제어합니다. 이 값은 어댑터에 의해 설정될 수 있습니다.

- `'file'`: Astro는 각 페이지 경로에 대해 이름이 지정된 HTML 파일을 생성합니다. (예를 들어 `src/pages/about.astro`와 `src/pages/about/index.astro`는 모두 `/about.html` 파일을 빌드합니다)
- `'directory'`: Astro는 각 페이지에 대해 중첩된 `index.html` 파일이 있는 디렉터리를 생성합니다. (예를 들어 `src/pages/about.astro`와 `src/pages/about/index.astro`는 모두 `/about/index.html` 파일을 빌드합니다)
- `'preserve'`: Astro는 소스 폴더에 나타나는 HTML 파일을 정확하게 생성합니다. (예를 들어 `src/pages/about.astro`는 `/about.html`을 빌드하고 `src/pages/about/index.astro`는 `/about/index.html` 파일을 빌드합니다.)

```js
{
  build: {
    // 예: 빌드 중에 `page/index.html` 대신 `page.html`을 생성합니다.
    format: 'file';
  }
}
```

#### Astro.url에 미치는 영향

`build.format`을 설정하면 빌드 중에 `Astro.url`이 무엇으로 설정될지 제어할 수 있습니다.

- `directory` - `Astro.url.pathname`에는 폴더 동작을 모방하기 위해 후행 슬래시가 포함됩니다. 즉 `/foo/`입니다.
- `file` - `Astro.url.pathname`에는 `.html`이 포함됩니다. 즉 `/foo.html`입니다.

이는 `new URL('./relative', Astro.url)`을 사용하여 상대 URL을 생성할 때 개발과 빌드 간에 일관된 동작을 얻게 된다는 것을 의미합니다.

개발에서 후행 슬래시 동작의 불일치를 방지하려면 빌드 형식에 따라 [`trailingSlash` 옵션](#trailingslash)을 `'always'` 또는 `'never'`로 제한할 수 있습니다.

- `directory` - `trailingSlash: 'always'`로 설정됩니다.
- `file` - `trailingSlash: 'never'`로 설정됩니다.

### build.client

<p>

**타입:** `string`<br />
**기본값:** `'./dist/client'`

</p>

`output: 'server'` 또는 `output: 'hybrid'`인 경우에만 클라이언트측 CSS 및 JavaScript의 출력 디렉터리를 제어합니다.
`outDir`은 코드가 빌드되는 위치를 제어합니다.

이 값은 `outDir`을 기준으로 합니다.

```js
{
  output: 'server', // 또는 'hybrid'
  build: {
    client: './client'
  }
}
```

### build.server

<p>

**타입:** `string`<br />
**기본값:** `'./dist/server'`

</p>

SSR로 빌드할 때 서버 JavaScript의 출력 디렉터리를 제어합니다.

이 값은 `outDir`을 기준으로 합니다.

```js
{
  build: {
    server: './server';
  }
}
```

### build.assets

<p>

**타입:** `string`<br />
**기본값:** `'_astro'`<br />

<Since v="2.0.0" />
</p>

Astro에서 생성된 자산 (예: JS 및 CSS 번들)이 있어야 하는 빌드 출력의 디렉터리를 지정합니다.

```js
{
  build: {
    assets: '_custom';
  }
}
```

**참고하기:**

- outDir

### build.assetsPrefix

<p>

**타입:** `string | Record.<string, string>`<br />
**기본값:** `undefined`<br />

<Since v="2.2.0" />
</p>

Astro에서 생성된 자산 링크의 접두사를 지정합니다. 자산이 현재 사이트와 다른 도메인에서 제공되는 경우 사용할 수 있습니다.

이를 위해서는 로컬 `./dist/_astro` 폴더의 자산을 원격 도메인의 해당 `/_astro/` 폴더에 업로드해야 합니다.

`_astro` 경로의 이름을 바꾸려면 `build.assets`에 새 디렉터리를 지정합니다.

동일한 도메인 (예: `https://cdn.example.com/_astro/...`)에 업로드된 모든 자산을 가져오려면 `assetsPrefix`를 루트 도메인의 문자열로 설정합니다. (`base` 구성에 관계없이):

```js
{
  build: {
    assetsPrefix: 'https://cdn.example.com';
  }
}
```
**추가:** `astro@4.5.0`

또한 `assetsPrefix`에 객체를 전달하여 각 파일 형식에 대해 서로 다른 도메인을 지정할 수도 있습니다.
이 경우 `fallback` 속성이 필요하며 기본적으로 다른 파일에 사용됩니다.

```js
{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}
```

### build.serverEntry

<p>

**타입:** `string`<br />
**기본값:** `'entry.mjs'`

</p>

SSR로 빌드할 때 서버 엔트리포인트의 파일 이름을 지정합니다.
이 엔트리포인트는 일반적으로 배포하려는 호스트에 따라 달라지며 어댑터에 의해 설정됩니다.

런타임에서 파일이 JavaScript 모듈임을 감지할 수 있도록 이 파일은 `.mjs`로 끝나는 것이 좋습니다.

```js
{
  build: {
    serverEntry: 'main.mjs';
  }
}
```

### build.redirects

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.6.0" />
</p>

빌드 중에 리디렉션을 HTML로 출력할지 여부를 지정합니다.
이 옵션은 `output: 'static'` 모드에만 적용됩니다. SSR 리디렉션에서는 모든 응답과 동일하게 처리됩니다.

이 옵션은 주로 리디렉션을 위한 특수 구성 파일이 있고 HTML 기반 리디렉션이 필요하지 않거나 필요하지 않은 어댑터에서 사용하기 위한 것입니다.

```js
{
  build: {
    redirects: false;
  }
}
```

### build.inlineStylesheets

<p>

**타입:** `'always' | 'auto' | 'never'`<br />
**기본값:** `auto`<br />

<Since v="2.6.0" />
</p>

프로젝트 스타일을 별도의 CSS 파일로 브라우저에 보낼지 `<style>` 태그에 인라인할지 제어합니다. 다음 옵션 중에서 선택하세요.

- `'always'` - 프로젝트 스타일은 `<style>` 태그에 인라인됩니다.
- `'auto'` - `ViteConfig.build.assetsInlineLimit` (기본값: 4kb)보다 작은 스타일시트만 인라인됩니다. 그렇지 않으면 프로젝트 스타일이 외부 스타일시트로 전송됩니다.
- `'never'` - 프로젝트 스타일은 외부 스타일시트로 전송됩니다.

```js
{
	build: {
		inlineStylesheets: `never`,
	},
}
```

## 서버 옵션

`astro dev`와 `astro preview` 모두에서 사용되는 Astro 개발 서버를 사용자 정의하세요.

```js
{
  server: { port: 1234, host: true}
}
```

실행 명령 ("dev", "preview")을 기반으로 다른 구성을 설정하려면 이 구성 옵션에 함수를 전달할 수도 있습니다.

```js
{
  // 예: 함수 구문을 사용하여 명령에 따라 사용자 정의
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 });
}
```

### server.host

<p>

**타입:** `string | boolean`<br />
**기본값:** `false`<br />

<Since v="0.24.0" />
</p>

서버가 수신해야 하는 네트워크 IP 주소 (예: 로컬 호스트가 아닌 IP)를 설정합니다.

- `false` - 네트워크 IP 주소를 노출하지 않습니다.
- `true` - LAN 및 공용 주소를 포함한 모든 주소에서 수신합니다.
- `[custom-address]` - `[custom-address]` (예: `192.168.0.1`)의 네트워크 IP 주소를 노출합니다.

### server.port

<p>

**타입:** `number`<br />
**기본값:** `4321`

</p>

서버가 수신해야 하는 포트를 설정합니다.

주어진 포트가 이미 사용 중이라면 Astro는 자동으로 다음 사용 가능한 포트를 시도합니다.

```js
{
  server: {
    port: 8080;
  }
}
```

### server.open

<p>

**타입:** `string | boolean`<br />
**기본값:** `false`<br />

<Since v="2.1.8" />
</p>

시작 시 개발 서버가 브라우저 창에서 열릴지 여부를 제어합니다.

열려는 URL을 지정하려면 전체 URL 문자열 (예: "http://example.com") 또는 경로 이름 (예: "/about")을 전달하세요.

```js
{
  server: {
    open: '/about';
  }
}
```

### server.headers

<p>

**타입:** `OutgoingHttpHeaders`<br />
**기본값:** `{}`<br />

<Since v="1.7.0" />
</p>

`astro dev` 및 `astro preview`에서 전송되도록 사용자 정의 HTTP 응답 헤더를 설정합니다.

## 개발 툴바 옵션

### devToolbar.enabled

<p>

**타입:** `boolean`<br />
**기본값:** `true`

</p>

Astro 개발 툴바를 활성화할지 여부입니다. 이 툴바를 사용하면 페이지 아일랜드를 검사하고 성능 및 접근성에 대한 유용한 정보를 볼 수 있습니다.

이 옵션은 전체 프로젝트로 범위가 지정되며, 자신에 대해서만 툴바를 비활성화하려면 `npm run astro preferences disable devToolbar`를 실행하세요. 모든 Astro 프로젝트에 대한 툴바를 비활성화하려면 `npm run astro preferences disable devToolbar --global`을 실행하세요.

## 프리페치 옵션

<p>

**타입:** `boolean | object`

</p>

더 빠른 페이지 전환을 제공하려면 사이트의 링크에 대해 프리페치를 활성화하세요.
(`<ViewTransitions />` 라우터를 사용하는 페이지에서는 기본적으로 활성화됩니다. 이 동작을 선택하지 않으려면 `prefetch: false`를 설정하세요.)

이 구성은 프로젝트의 모든 페이지에 프리페치 스크립트를 자동으로 추가하여 `data-astro-prefetch` 속성에 대한 액세스를 제공합니다.
해당 페이지에 대한 프리페칭을 활성화하려면 페이지의 `<a />` 링크에 이 속성을 추가하세요.

```html
<a href="/about" data-astro-prefetch>About</a>
```

[`prefetch.defaultStrategy`](#prefetchdefaultstrategy) 및 [`prefetch.prefetchAll`](#prefetchprefetchall) 옵션을 사용하여 기본 프리페치 동작을 추가로 사용자 정의하세요.

자세한 내용은 [프리페치 안내서](/ko/guides/prefetch/)를 참조하세요.

### prefetch.prefetchAll

<p>

**타입:** `boolean`

</p>

`data-astro-prefetch` 속성이 없는 링크를 포함하여 모든 링크에 대해 프리페치를 활성화합니다.
`<ViewTransitions />` 라우터를 사용할 때 이 값의 기본값은 `true`입니다. 그렇지 않은 경우 기본값은 `false`입니다.

```js
prefetch: {
  prefetchAll: true;
}
```

`true`로 설정하면 개별 링크에 `data-astro-prefetch="false"`를 설정하여 프리페치를 개별적으로 비활성화할 수 있습니다.

```html
<a href="/about" data-astro-prefetch="false">About</a>
```

### prefetch.defaultStrategy

<p>

**타입:** `'tap' | 'hover' | 'viewport' | 'load'`<br />
**기본값:** `'hover'`

</p>

`data-astro-prefetch` 속성이 없는 링크에 설정된 경우 사용할 기본 프리페치 전략입니다.

- `'tap'`: 링크를 클릭하기 직전에 미리 가져옵니다.
- `'hover'`: 링크 위로 마우스를 가져가거나 링크에 초점을 맞추면 미리 가져옵니다. (기본값)
- `'viewport'`: 링크가 뷰포트에 들어갈 때 미리 가져옵니다.
- `'load'`: 페이지가 로드된 후 페이지의 모든 링크를 미리 가져옵니다.

속성에 값을 설정하여 이 기본값을 무시하고 개별 링크에 대해 다른 전략을 선택할 수 있습니다.

```html
<a href="/about" data-astro-prefetch="viewport">About</a>
```

## 이미지 옵션

### image.endpoint

<p>

**타입:** `string`<br />
**기본값:** `undefined`<br />

<Since v="3.1.0" />
</p>

개발 및 SSR에서 이미지 최적화에 사용할 엔드포인트를 설정합니다. 기본 엔드포인트를 사용하려면 `undefined`로 설정하세요.

엔드포인트는 항상 `/_image`에 삽입됩니다.

```js
{
  image: {
    // 예: 사용자 정의 이미지 엔드포인트 사용
    endpoint: './src/image-endpoint.ts',
  },
}
```

### image.service

<p>

**타입:** `Object`<br />
**기본값:** `{entrypoint: 'astro/assets/services/sharp', config?: {}}`<br />

<Since v="2.1.0" />
</p>

Astro의 자산 지원에 사용되는 이미지 서비스를 설정합니다.

값은 이미지 서비스가 사용할 엔트리포인트가 있는 객체여야 하며 선택적으로 서비스에 전달할 구성 객체여야 합니다.

서비스 엔트리포인트는 포함된 서비스 중 하나이거나 타사 패키지일 수 있습니다.

```js
{
  image: {
    // 예: 사용자 정의 구성으로 Sharp 기반 이미지 서비스 활성화
    service: {
			 entrypoint: 'astro/assets/services/sharp',
			 config: {
				 limitInputPixels: false,
      },
		 },
  },
}
```

#### image.service.config.limitInputPixels

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="4.1.0" />
</p>

Sharp 이미지 서비스가 처리할 이미지 크기를 제한할지 여부입니다.

Sharp 이미지 서비스의 기본 이미지 크기 제한을 우회하고 큰 이미지를 처리하려면 `false`를 설정하세요.

### image.domains

<p>

**타입:** `Array.<string>`<br />
**기본값:** `{domains: []}`<br />

<Since v="2.10.10" />
</p>

원격 이미지 최적화를 위해 허용되는 이미지 소스 도메인 목록을 정의합니다. 다른 원격 이미지는 Astro에서 최적화되지 않습니다.

이 옵션에는 개별 도메인 이름의 배열이 문자열로 필요합니다. 와일드카드는 허용되지 않습니다. 대신 [`image.remotePatterns`](#imageremotepatterns)를 사용하여 허용되는 소스 URL 패턴 목록을 정의하세요.

```js
// astro.config.mjs
{
  image: {
    // 예: 단일 도메인에서 원격 이미지 최적화 허용
    domains: ['astro.build'],
  },
}
```

### image.remotePatterns

<p>

**타입:** `Array.<RemotePattern>`<br />
**기본값:** `{remotePatterns: []}`<br />

<Since v="2.10.10" />
</p>

원격 이미지 최적화를 위해 허용되는 이미지 소스 URL 패턴 목록을 정의합니다.

`remotePatterns`는 네 가지 속성으로 구성할 수 있습니다.

1. protocol
2. hostname
3. port
4. pathname

```js
{
  image: {
    // 예: aws s3 버킷의 모든 이미지 처리를 허용합니다.
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}
```

아래 설명과 같이 와일드카드를 사용하여 허용되는 `hostname` 및 `pathname` 값을 정의할 수 있습니다. 그렇지 않으면 제공된 정확한 값만 구성됩니다.

`hostname`:

- '\*\*' 로 시작하면 모든 하위 도메인 ('endsWith')을 허용합니다.
- '\*' 로 시작하면 한 수준의 하위 도메인만 허용합니다.

`pathname`:

- 모든 하위 경로 ('startsWith')를 허용하려면 '/\*\*' 로 끝납니다.
- 한 수준의 하위 경로만 허용하려면 '/\*' 로 끝납니다.

## Markdown 옵션

### markdown.shikiConfig

<p>

**타입:** `Partial<ShikiConfig>`

</p>

Shiki 구성 옵션. 사용법은 [Markdown 구성 문서](/ko/guides/markdown-content/#shiki-구성)를 참조하세요.

### markdown.syntaxHighlight

<p>

**타입:** `'shiki' | 'prism' | false`<br />
**기본값:** `shiki`

</p>

사용할 구문 강조 표시 (있는 경우)

- `shiki` - [Shiki](https://shiki.style)를 사용합니다.
- `prism` - [Prism](https://prismjs.com/)을 사용합니다.
- `false` - 구문 강조를 적용하지 않습니다.

```js
{
  markdown: {
    // 예: Markdown에서 구문 강조를 위해 Prism을 사용하도록 전환
    syntaxHighlight: 'prism',
  }
}
```

### markdown.remarkPlugins

<p>

**타입:** `RemarkPlugins`

</p>

[remark 플러그인](https://github.com/remarkjs/remark)을 전달하여 Markdown 빌드 방법을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

```js
import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [remarkToc];
  }
}
```

### markdown.rehypePlugins

<p>

**타입:** `RehypePlugins`

</p>

[rehype 플러그인](https://github.com/remarkjs/remark-rehype)을 전달하여 Markdown의 출력 HTML이 처리되는 방식을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

```js
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis];
  }
}
```

### markdown.gfm

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.0.0" />
</p>

Astro는 기본적으로 [GitHub 기반 Markdown](https://github.com/remarkjs/remark-gfm)을 사용합니다. 이를 비활성화하려면 `gfm` 플래그를 `false`로 설정하세요.

```js
{
  markdown: {
    gfm: false,
  }
}
```

### markdown.smartypants

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="2.0.0" />
</p>

Astro는 기본적으로 [SmartyPants 포매터](https://daringfireball.net/projects/smartypants/)를 사용합니다. 이를 비활성화하려면 `smartypants` 플래그를 `false`로 설정하세요.

```js
{
  markdown: {
    smartypants: false,
  }
}
```

### markdown.remarkRehype

<p>

**타입:** `RemarkRehype`

</p>

옵션을 [remark-rehype](https://github.com/remarkjs/remark-rehype#api)에 전달하세요.

```js
{
  markdown: {
    // 예: 각주 텍스트를 다른 언어로 번역합니다. 기본 영어 값은 다음과 같습니다.
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};
```

## i18n

<p>

**타입:** `object`<br />

<Since v="3.5.0" />
</p>

i18n 라우팅을 구성하고 일부 맞춤 옵션을 지정할 수 있습니다.

[Astro의 국제화](/ko/guides/internationalization/)에 대한 자세한 내용은 안내서를 참조하세요.

### i18n.defaultLocale

<p>

**타입:** `string`<br />

<Since v="3.5.0" />
</p>

웹사이트/애플리케이션의 기본 언어입니다. 필수 필드입니다.

특정 언어 형식이나 구문이 적용되지는 않지만 호환성을 극대화하려면 필요에 따라 소문자와 하이픈 (예: "es", "pt-br")을 사용하는 것이 좋습니다.

### i18n.locales

<p>

**타입:** `Locales`<br />

<Since v="3.5.0" />
</p>

`defaultLocale`을 포함하여 웹사이트에서 지원하는 모든 언어의 목록입니다. 필수 필드입니다.

언어는 개별 코드 (예: `['en', 'es', 'pt-br']`)로 나열되거나 공유된 코드 `path` (예: `{ path: "english", codes: ["en", "en-US"]}`)에 매핑될 수 있습니다. 이 코드는 배포된 사이트의 URL 구조를 결정하는 데 사용됩니다.

특정 언어 코드 형식이나 구문은 적용되지 않지만 콘텐츠 파일이 포함된 프로젝트 폴더는 목록의 `locales` 항목과 정확히 일치해야 합니다. 맞춤 URL 경로 접두사를 가리키는 여러 `codes`가 있는 경우 구성된 `path`와 동일한 이름을 가진 폴더에 콘텐츠 파일을 저장하세요.

### i18n.fallback

<p>

**타입:** `Record.<string, string>`<br />

<Since v="3.5.0" />
</p>

존재하지 않는 페이지로 이동할 때의 대체 전략 (예: 번역된 페이지가 생성되지 않음)

이 객체를 사용하여 지원하는 각 언어에 대한 대체 `locale` 경로를 선언하세요. 대체가 지정되지 않으면 사용할 수 없는 페이지는 404를 반환합니다.

##### 예

다음 예시는 `/pt-br/`에서 사용할 수 없는 페이지를 `es` 버전으로 리디렉션하고, `/fr/`에서 사용할 수 없는 페이지를 `en` 버전으로 리디렉션하도록 콘텐츠 대체 전략을 구성합니다. 사용할 수 없는 `/es/` 페이지는 404를 반환합니다.

```js
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'pt-br', 'es'],
    fallback: {
      pt: 'es',
      fr: 'en',
    },
  },
});
```

### i18n.routing

<p>

**타입:** `Routing`<br />

<Since v="3.7.0" />
</p>

사이트 URL을 결정하기 위한 라우팅 전략을 제어합니다. 기본 언어에 대한 폴더/URL 경로 구성을 기반으로 이를 설정합니다.

#### i18n.routing.prefixDefaultLocale

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="3.7.0" />
</p>

`false`인 경우 기본이 아닌 언어에만 언어 접두사가 표시됩니다.
`defaultLocale`은 언어 접두사를 표시하지 않으며, 콘텐츠 파일은 현지화된 폴더에 존재하지 않습니다.
URL은 기본이 아닌 모든 언어의 경우 `example.com/[locale]/content/` 형식이지만 기본 언어의 경우 `example.com/content/` 형식입니다.

`true`인 경우 모든 URL에 언어 접두사가 표시됩니다.
URL은 기본 언어를 포함하여 모든 경로에 대해 `example.com/[locale]/content/` 형식입니다.
현지화된 폴더는 기본값을 포함하여 모든 언어에 사용됩니다.

#### i18n.routing.redirectToDefaultLocale

<p>

**타입:** `boolean`<br />
**기본값:** `true`<br />

<Since v="4.2.0" />
</p>

`prefixDefaultLocale: true`가 설정된 경우 `src/pages/index.astro`에 의해 생성된 홈 URL (`/`)이 `/[defaultLocale]`로 리디렉션되는지 여부를 구성합니다.

사이트 루트에서 자동 리디렉션을 비활성화하려면 `redirectToDefaultLocale: false`를 설정하세요.

```js
// astro.config.mjs
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false,
    },
  },
});
```

## Legacy 플래그

일부 사용자가 Astro 버전 간에 마이그레이션할 수 있도록 돕기 위해 때때로 `legacy` 플래그를 도입합니다.
이러한 플래그를 사용하면 최신 버전에서 더 이상 사용되지 않거나 오래된 Astro의 동작을 선택할 수 있으므로 계속 업그레이드하고 새로운 Astro 릴리스를 활용할 수 있습니다.

## Experimental 플래그

Astro는 사용자가 새로운 기능에 조기에 액세스할 수 있도록 experimental 플래그를 제공합니다.
이러한 플래그는 안정성이 보장되지 않습니다.

### experimental.directRenderScript

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="4.5.0" />
</p>

스크립트가 사용되지 않는 페이지에서 스크립트가 실행되는 것을 방지하기 위해 보다 안정적인 전략을 가능하게 합니다.

스크립트는 Astro 파일에 선언된 대로 직접 렌더링됩니다. (TypeScript, `node_modules` 가져오기, 중복 제거 스크립트 등 기존 기능 포함) 이제 Astro 파일에서 조건부로 스크립트를 렌더링할 수도 있습니다.
그러나 이는 스크립트가 더 이상 `<head>`로 끌어올려지지 않으며 페이지의 여러 스크립트가 더 이상 번들링되지 않음을 의미합니다.
이 옵션을 활성화하면 모든 `<script>` 태그가 예상대로 작동하는지 확인해야 합니다.

이 옵션은 Astro 4.5.0에서 기본적으로 활성화됩니다.

```js
{
  experimental: {
    directRenderScript: true,
  },
}
```

### experimental.contentCollectionCache

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="3.5.0" />
</p>

정적 모드에서 빌드할 때 콘텐츠 컬렉션에 대한 영구 캐시를 활성화합니다.

```js
{
	experimental: {
		contentCollectionCache: true,
	},
}
```

### experimental.contentCollectionJsonSchema

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />
<Since v="4.5.0" />
</p>

이 기능은 VSCode와 같은 도구에서 TypeScript 스타일 자동 완성/힌트에 대한 `$schema` 값으로 사용할 수 있는 `type: 'data'` 콘텐츠 컬렉션에 대한 JSON 스키마를 자동으로 생성합니다.

이 기능을 활성화하려면 experimental 플래그를 추가하세요.

```diff
import { defineConfig } from 'astro/config';
export default defineConfig({
	experimental: {
+		contentCollectionJsonSchema: true
	}
});
```

이 실험적 구현에서는 컬렉션의 각 데이터 항목 파일에 있는 스키마를 수동으로 참조해야 합니다.

```diff
// src/content/test/entry.json
{
+  "$schema": "../../../.astro/collections/test.schema.json",
	"test": "test"
}
```

또는 [VSCode `json.schemas` 설정](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings)에서 이를 설정할 수 있습니다.

```diff
"json.schemas": [
	{
		"fileMatch": [
			"/src/content/test/**"
		],
		"url": "../../../.astro/collections/test.schema.json"
	}
]
```

이 초기 구현은 [고급 Zod 스키마에 대해 알려진 문제](https://github.com/StefanTerdell/zod-to-json-schema#known-issues)가 있는 라이브러리를 사용하므로 실험적 플래그를 활성화하기 전에 이러한 제한 사항을 참조하는 것이 좋습니다.

### experimental.clientPrerender

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="4.2.0" />
</p>

지원되는 브라우저의 클라이언트에서 미리 가져온 페이지를 사전 렌더링할 수 있습니다.

이 기능은 실험적인 [Speculation Rules Web API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)를 사용하여 기본 `prefetch` 동작을 전역적으로 향상시켜 클라이언트에서 링크를 사전 렌더링합니다.
이 기능을 활성화하기 전에 [클라이언트에서 사전 렌더링할 때 발생할 수 있는 위험](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API#unsafe_prefetching)을 검토하는 것이 좋습니다.

원하는 `prefetch` 구성 옵션과 함께 `astro.config.mjs` 파일에서 클라이언트 측 사전 렌더링을 활성화하세요.

```js
// astro.config.mjs
{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
	experimental: {
		clientPrerender: true,
	},
}
```

프리페치를 선택하려면 사이트의 `<a />` 링크에서 `data-astro-prefetch` 속성을 계속 사용하세요.
문서 헤드에 `<link>` 태그를 추가하거나 JavaScript로 페이지를 가져오는 대신 `<script>` 태그에 해당 speculation rules이 추가됩니다.

클라이언트 측 사전 렌더링에는 브라우저 지원이 필요합니다. Speculation Rules API가 지원되지 않는 경우 `prefetch`는 지원되는 전략으로 대체됩니다.

더 많은 `prefetch` 옵션 및 사용법은 [프리페치 가이드](/ko/guides/prefetch/)를 참조하세요.

### experimental.globalRoutePriority

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="4.2.0" />
</p>

모든 경로에 대해 동일한 [경로 우선 순위 규칙](/ko/guides/routing/#경로-우선순위)을 따라 파일 기반 프로젝트 경로와 함께 리디렉션 및 삽입된 경로의 우선 순위를 동일하게 지정합니다.

이를 통해 특정 유형의 경로에 자동으로 우선순위를 지정하지 않음으로써 프로젝트의 경로를 보다 효과적으로 제어할 수 있으며 모든 경로에 대한 경로 우선순위 순서를 표준화합니다.

다음 예시에서는 파일 기반 경로, 삽입된 경로 및 리디렉션이 결합될 때 어떤 경로가 특정 페이지 URL을 빌드하는지 보여줍니다.

- 파일 기반 경로: `/blog/post/[pid]`
- 파일 기반 경로: `/[page]`
- 삽입된 경로: `/blog/[...slug]`
- 리디렉션: `/blog/tags/[tag]` -> `/[tag]`
- 리디렉션: `/posts` -> `/blog`

`experimental.globalRoutingPriority`를 활성화한 경우 (Astro 4.0 기본 경로 우선 순위 대신):

- `/blog/tags/astro`는 `/tags/[tag]`로의 리디렉션에 의해 빌드됩니다. (삽입된 경로인 `/blog/[...slug]` 대신)
- `/blog/post/0`은 파일 기반 경로인 `/blog/post/[pid]`에 의해 빌드됩니다. (삽입된 경로인 `/blog/[...slug]` 대신)
- `/posts`는 `/blog`로의 리디렉션에 의해 빌드됩니다. (파일 기반 경로인 `/[page]` 대신)

경로 우선순위가 동일한 두 경로가 동일한 URL을 빌드하려고 시도하는 경로 충돌이 발생하는 경우 Astro는 충돌하는 경로를 식별하는 경고를 기록합니다.

### experimental.i18nDomains

<p>

**타입:** `boolean`<br />
**기본값:** `false`<br />

<Since v="4.3.0" />
</p>

사용자 정의 도메인 (또는 하위 도메인)을 사용하도록 하나 이상의 지원 언어의 URL 패턴을 구성할 수 있는 [실험적 `domains` 라우팅 전략](/ko/guides/internationalization/#domains-실험적)에 대한 지원을 활성화합니다.

로케일이 도메인에 매핑되면 `/[locale]/` 경로 접두사가 사용되지 않습니다. 그러나 구성된 `defaultLocale`을 포함하여 `src/pages/` 내 현지화된 폴더는 여전히 필요합니다.

구성되지 않은 다른 로케일은 `prefixDefaultLocale` 전략 (예: `https://example.com/[locale]/blog`)에 따라 현지화된 경로 기반 URL로 기본 설정됩니다.

```js
//astro.config.mjs
export default defineConfig({
	site: "https://example.com",
	output: "server", // 필수, 사전 렌더링된 페이지 없음
  adapter: node({
    mode: 'standalone',
  }),
	i18n: {
		defaultLocale: "en",
		locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
		  domains: {
			  fr: "https://fr.example.com",
			  es: "https://example.es"
   },
 experimental: {
    i18nDomains: true
 }
})
```

빌드된 페이지 경로와 `astro:i18n` 도우미 함수 [`getAbsoluteLocaleUrl()`](/ko/guides/internationalization/#getabsolutelocaleurl) 및 [`getAbsoluteLocaleUrlList()`](/ko/guides/internationalization/#getabsolutelocaleurllist)에 의해 반환된 URL은 모두 `i18n.domains`에 설정된 옵션을 사용합니다.

이 실험적 기능의 제한 사항을 포함한 자세한 내용은 [국제화 가이드](/ko/guides/internationalization/#domains-실험적)를 참조하세요.
